home *** CD-ROM | disk | FTP | other *** search
/ NEXT Generation 23 / NEXT23.iso / mac / Media / DATABASE.Cxt / 00015_Field_FileIO Xtra Information.txt < prev    next >
Text File  |  1996-09-12  |  11KB  |  318 lines
  1. FileIO Xtra
  2. Version 1.0.1 - 24may96 CH
  3.  
  4. FileIO Xtra for Macromedia Director 5.0
  5. =======================================
  6.  
  7. FileIO provides a set of methods allowing users of Macromedia Director 5.0 to
  8. programmatically access files using the Lingo scripting language. 
  9.  
  10. Changes from Previous Versions
  11. ===============================
  12.  
  13. The FileIO Xtra no longer requires the FileSupport Xtra to function. These files can
  14. now be removed from the Xtra's folder. They are: FILESUPT.X16, FILESUPT.X32 and
  15. FileSupport.
  16.  
  17. Various methods have been updated to support double-byte character sets with a few
  18. limitations. See the method reference section for more information.
  19.  
  20. Using FileIO
  21. ============
  22.  
  23. If automatic opening is desired, place a copy of the FileIO Xtra for your platform
  24. into either the system Xtra's or Application Xtra's folder. If automatic opening is
  25. not desired, the Xtra can be placed anywhere and opened using Lingo's 'openXLib'
  26. command. This applies to projector's as well, with one exception: If automatic
  27. opening of the Xtra is desired, it must be placed in an Xtra's folder in the same
  28. folder as the projector.
  29.  
  30. Each instance of FileIO can reference a single open file. If multiple files are to
  31. be opened simultaneously, a new instance of FileIO is required for each opened file.
  32. A single instance can be used to open multiple files, as long as the file is closed
  33. before a new file is opened. To create a new instance, use the new() method, defined
  34. below. To dispose of an instance, set the instance variable to 0. All methods that
  35. read from or write to the file must be called after the file has been opened using
  36. the openFile() method. If a new file is to be opened using the same instance, the
  37. file must be closed using closeFile(). Files can be opened in three different modes:
  38. Read, Write and Read/Write. When writing to a file, the contents of the file after
  39. the current position are overwritten.
  40.  
  41. Example Lingo
  42.  
  43.  set myFile = new(xtra "fileio")      -- Create an instance of FileIO
  44.  set fileName = displayOpen(myFile)   -- Display Open Dialog and return the fileName
  45.  openFile(myFile, fileName, 1)        -- Open the file
  46.  set theFile = readFile(myFile)       -- Read the file and return a string to Lingo
  47.  closeFile(myFile)                    -- Close the file
  48.  set myFile = 0                       -- Dispose of the instance
  49.  
  50. In this example, we created a new instance and stored it in the variable myFile.
  51. Next, the displayOpen() method is used to display an open dialog to allow a file to
  52. be chosen. The file is returned as a fully-qualified path string to Lingo. The file
  53. is then opened in read only mode, the contents of the file are read, and the file is
  54. closed. Lastly, the instance is disposed of.
  55.  
  56. Known Problems
  57. ==============
  58.  
  59. The createFile() method does not support relative filenames, or the Lingo '@' 
  60. operator in pathnames. This will be fixed in a later version.
  61.  
  62. The displaySave() method does not directly inform Lingo whether a user is 
  63. replacing an existing file. The workaround is to attempt to create the file using
  64. createFile() and check the error code for a "File Already Exists" error.
  65.  
  66. History
  67. =======
  68.  
  69. 27may96 (v1.0.1)
  70.  
  71. Fixed crash when using displaySave() method under Windows NT.
  72. Fixed various problems when using read/write mode.
  73. Fixed problem with writeString() only writing out the first 256 characters of a string. 
  74. Fixed the setFilterMask() method to correctly reset the filter mask on Windows. 
  75. Fixed readToken() so chunks larger than 256 characters are properly returned to Lingo. 
  76. Fixed a problem causing SoundEdit 16 to crash if FileIO was in the System Xtras folder.
  77. Added support for double-byte character sets.
  78. Added version() method to report FileIO Xtra version information. 
  79. Added getOSDir() to return a full path to the Windows Directory/System Folder.
  80.  
  81. 15mar96 (v1.0.0 Beta)
  82.  
  83. First public release.
  84.  
  85. Method Reference
  86. ================
  87.  
  88. The first line of each definition contains the method name, a list of parameters and
  89. thier value types. The internal name of the FileIO Xtra is "fileio". This name is
  90. used whenever referencing the xtra using the form 'xtra "fileio"'.
  91.  
  92. New methods will appear at the bottom of this list.
  93.  
  94. ---
  95.  
  96. mMessageList( xtra reference )
  97.  
  98. Returns a list of methods and parameters, as well as a brief explanation of each.
  99.  
  100. ---
  101.  
  102. new( xtra reference )
  103.  
  104. This is called to create a new instance of FileIO. The Xtra can be referenced by name
  105. or number. It returns an instance variable used to reference the instance.
  106.  
  107. ---
  108.  
  109. fileName( instance )
  110.  
  111. Returns the fileName string of the current open file.  The file must be open use this
  112. method.
  113.  
  114. ---
  115.  
  116. status( instance )
  117.  
  118. Returns the error code returned by the last method called. The value is returned as
  119. an integer. 
  120.  
  121. ---
  122.  
  123. error( instance, int error )
  124.  
  125. Returns a readable error string. A numeric error code is passed in as the
  126. second argument. The errors returned can be any of the following:
  127.  
  128. "OK"
  129. "Memory allocation failure"
  130. "File directory full"
  131. "Volume full"
  132. "Volume not found"
  133. "I/O Error"
  134. "Bad file name"
  135. "File not open"
  136. "Too many files open"
  137. "File not found"
  138. "No such drive"
  139. "No disk in drive"
  140. "Directory not found"
  141. "Instance has an open file"
  142. "File already exists"
  143. "File is opened read-only"
  144. "File is opened write-only"
  145. "Unknown error"
  146.  
  147. ---
  148.  
  149. setFilterMask( instance, string mask )
  150.  
  151. Sets the filter mask used by calls to displayOpen() and displaySave(). The filter
  152. mask determines what files to show when displaying an Open or Save dialog. The second
  153. parameter is a string representing the filter mask to set. On Windows, this is a
  154. comma seperated string of file types and associated extensions (e.g. "All
  155. Files,*.*,Text Files,*.TXT"), and a string of types on the Macintosh (e.g.
  156. "TEXTPICT"). On Windows, the filter mask string is limited to 256 characters. On the
  157. Macintosh, you are limited to four four-character types.  When a new instance of
  158. FileIO is created, the filter masks defaults to all files. To reset the filter mask to
  159. display all files after it has been set, just pass in an empty string (e.g.
  160. setFilterMask(me, "")).
  161.  
  162. ---
  163.  
  164. openFile( instance, string fileName, int openMode )
  165.  
  166. Opens the named file. This call must be used before any read/write operations can
  167. take place. The filename can be either a fully-qualified path and filename, or a
  168. relative filename. The Lingo '@' pathname operator is supported. The openMode
  169. parameter specifies whether to open the file in Read, Write or ReadWrite mode. Valid
  170. Flags are: 0 Read/Write, 1 Read, 2 Write.
  171.  
  172. ---
  173.  
  174. closeFile( instance )
  175.  
  176. Closes a file that has been previously opened using the openFile() method.
  177.  
  178. ---
  179.  
  180. displayOpen( instance )
  181.  
  182. Displays a platform specific Open dialog allowing a user to specify a file. Returns a
  183. fully-qualified path and fileName to Lingo. The setFilterMask() method can be used to
  184. control what file types are displayed in the dialog.
  185.  
  186. ---
  187.  
  188. displaySave( instance, string title, string defaultFileName )
  189.  
  190. Displays a platform specific Save dialog allowing a user to specify a file. Returns a
  191. fully-qualified path and fileName to Lingo. The setFilterMask() method can be used to
  192. control what file types are displayed in the dialog. The string and defaultFileName 
  193. parameters allow you to specifiy a default filename to be displayed, as well as title
  194. text for the save dialog. 
  195.  
  196. ---
  197.  
  198. createFile( instance, string fileName )
  199.  
  200. Creates a file. The fileName must be either a fileName to be created in the current
  201. directory, or a fully-qualified path and fileName. The Lingo '@' pathname operator
  202. and relative paths are not supported. After creating the new file, the file must be
  203. opened before it can be written to.
  204.  
  205. ---
  206.  
  207. setPosition( instance, position )
  208.  
  209. Sets the file position of the current open file. The file must be open to use this 
  210. method.
  211.  
  212. ---
  213.  
  214. getPosition( instance )
  215.  
  216. Gets the file position of the current open file. Returned as an integer. The file
  217. must be open to use this method. 
  218.  
  219. ---
  220.  
  221. getLength( instance )
  222.  
  223. Gets the length of the currently opened file. Returned as an integer. The file must
  224. be open use this method. The value returned is the length of the file in bytes. 
  225.  
  226. ---
  227.  
  228. writeChar( instance, string theChar )
  229.  
  230. Writes a single character to the file at the current position. The file must be open
  231. in write or read/write mode to use this method.
  232.  
  233. ---
  234.  
  235. writeString( instance, string theString )
  236.  
  237. Writes a string to the file at the current position. The file must be open in write
  238. or read/write mode to use this method.
  239.  
  240. ---
  241.  
  242. readChar( instance )
  243.  
  244. Reads the character (either single or double-byte) at the current position and then 
  245. increments the position. The character is returned to Lingo as a string. The file must 
  246. be open in read or read/write mode to use this method. 
  247.  
  248. ---
  249.  
  250. readLine( instance )
  251.  
  252. Reads from the current position up to and including the next CR, increments the
  253. position, and returns the string to Lingo.  The file must be open in read or
  254. read/write mode to use this method. 
  255.  
  256. ---
  257.  
  258. readFile( instance )
  259.  
  260. Reads from the current position to the end of the file and returns the file to Lingo
  261. as a string.  The file must be open in read or read/write mode to use this method.
  262.  
  263. ---
  264.  
  265. readWord( instance )
  266.  
  267. Reads the next word starting at the current position.  The file must be open in read
  268. or read/write mode to use this method. 
  269.  
  270. ---
  271.  
  272. readToken( instance, string skipChar, string breakChar )
  273.  
  274. Reads the next 'token' starting at the current position. Characters matching the
  275. skipChar parameter are "skipped" and the file is read until breakChar is encountered.
  276. The file must be open in read or read/write mode to use this method. This method will
  277. read double-byte tokens as long as the skip and break are single-byte characters. It
  278. will not detect double-byte skip or break characters.
  279.  
  280. ---
  281.  
  282. getFinderInfo( instance )
  283.  
  284. Returns the Type and Creator of the current file as a string. This method does
  285. nothing when used under Windows.  The file must be open to use this method.
  286.  
  287. ---
  288.  
  289. setFinderInfo( instance, string typeAndCreator )
  290.  
  291. Sets the Type and Creator of the current file. The string takes the form of a space
  292. seperated set of TYPE and CREATOR codes (e.g. "TEXTTTXT"). This method does nothing
  293. when used under Windows.  The file must be open to use this method.
  294.  
  295. ---
  296.  
  297. delete( instance )
  298.  
  299. Deletes the currently opened file.  The file must be open use this method.
  300.  
  301. ---
  302.  
  303. version( xtraRef )
  304.  
  305. Returns FileIO version and build information. Useful when filing 
  306. bug reports, determing installed version while authoring, etc. No practical use beyond this.
  307.  
  308. ---
  309.  
  310. getOSDir( )
  311.  
  312. Global method that returns the full path to either the Windows directory, or the System Folder 
  313. depending on which OS is currently being used. Does not require a child instance or
  314. Xtra reference to call.
  315.  
  316. ---
  317.  
  318.